Linked issue

Refs TML-2596

At a glance

// Forward page (newest first).
const firstPage = await db.Post
  .orderBy((post) => post.createdAt.desc())
  .take(10)
  .all();

// Backward page: same sort, flipped — no value-level OrderByItem import needed.
const lastPage = await db.Post
  .orderBy((post) => post.createdAt.desc().reverse())
  .take(10)
  .all();

Before this PR, OrderByItem exposed no inversion path. An integration that owns pagination (Relay backward cursors, REST list endpoints) could only new OrderByItem(item.expr, item.dir === 'asc' ? 'desc' : 'asc') against the internal @prisma-next/sql-relational-core/ast package — or abandon the chain API entirely, which is what the Pothos and Drizzle plugins ended up doing.

Decision

Add an instance method OrderByItem.prototype.reverse() that returns a new frozen item with the direction flipped (asc ⇄ desc) and expr unchanged. Direction is 'asc' | 'desc' only (no NULLS FIRST/LAST yet), so a single-axis flip is unambiguous.

That's the whole API. Because .reverse() is an instance method, an integration flips a sort by calling it on the item the orderBy selector already returns (selector(post).reverse()) — it never has to name or import OrderByItem at the value level. So this PR deliberately does not re-export OrderByItem from @prisma-next/sql-orm-client (see Alternatives).

How it fits together

1. Add reverse() to the OrderByItem class in relational-core/src/ast/types.ts. It reuses the frozen-class constructor, so the returned item carries the same immutability guarantees as .asc() / .desc().
2. Document the backward-pagination pattern in the ORM README, reversing inside the orderBy selector (the form the chain API accepts) — no AST import in the example.

Behavior changes & evidence

• OrderByItem.reverse() returns a new frozen item with the opposite direction and the same expr reference — types.ts. Covered by the round-trip + frozen-identity runtime cases in order.test.ts, with the public type shape (reverse(): OrderByItem, readable dir/expr) locked by order.types.test-d.ts.

Reviewer notes

• This started out re-exporting OrderByItem (per the ticket's original proposal). On review we dropped that: it would single out two AST types (OrderByItem, Direction) from the whole alphabet that otherwise lives only in sql-relational-core/ast, and .reverse() as an instance method removes the need for a value-level import anyway. The type test therefore lives in relational-core next to the runtime test, not in sql-orm-client.
• This is public API for extension authors, so it's covered by both a runtime unit test and a type-level test.

Compatibility / migration / risk

Purely additive — one new method. No existing signatures change; no migration needed.

Verification

• pnpm --filter @prisma-next/sql-relational-core test — 289 passed
• pnpm --filter @prisma-next/sql-relational-core typecheck — clean (includes the new .test-d.ts)
• pnpm --filter @prisma-next/sql-orm-client test — 505 passed, 3 skipped; type tests: no errors

Alternatives considered

• Re-exporting OrderByItem / Direction from @prisma-next/sql-orm-client (the ticket's original step 2). Rejected: it exposes a two-type slice of the AST alphabet from the ORM surface while every other AST type stays in sql-relational-core/ast — an inconsistent boundary. .reverse() makes the re-export unnecessary for the runtime path; consumers that want the type for annotations can still name it from sql-relational-core/ast.
• A static OrderByItem.invert(item) helper instead of an instance method. The instance method composes naturally with the chain API and matches the existing .asc() / .desc() ergonomics, so it's the more discoverable surface.
• Also accepting a user-supplied option-shape orderBy: [...] (what Hayes built in his plugin). A separate design question tracked as a follow-up; this PR only fills the immediate gap in the chain API.

Checklist

• All commits are signed off (git commit -s) per the DCO.
• I read CONTRIBUTING.md and the change is scoped to one logical concern.
• Tests are updated.
• The PR title is in TML-NNNN: <sentence-case title> form.
• The Skill update section is addressed (n/a — see below).

Skill update

n/a — this adds a public method covered by README and tests; no CLI/config/error-code surface changed that the agent skills track.

Summary by CodeRabbit

• New Features

  • Added reverse() method to invert sort direction (asc ↔ desc) for sort order definitions.

• Documentation

  • Updated pagination guide with examples demonstrating sort direction reversal for cursor-based navigation scenarios.

• Tests

  • Added test coverage validating sort reversal behavior and type correctness.